Azure Blob Storage - Anexos - Documentação v2.0

Visão Geral

Este documento descreve a implementação atualizada do Azure Blob Storage para gerenciamento de anexos na API CordenaAi com contêineres hierárquicos por ambiente. O sistema permite upload, download, listagem e gerenciamento de arquivos com separação automática entre desenvolvimento e produção.

Arquitetura

Componentes Principais

1. AnexosBlobController - Controller REST para operações de anexos
2. AnexoBlobService - Serviço de negócio para operações de blob
3. BlobStorageService - Serviço de infraestrutura para Azure Storage
4. DTOs - Objetos de transferência de dados

Fluxo de Dados

Cliente → AnexosBlobController → AnexoBlobService → BlobStorageService → Azure Storage

Configuração v2.0 - Contêineres Hierárquicos

1. Configuração por Ambiente

appsettings.Development.json

{
  "ConnectionStrings": {
    "AzureStorage": "DefaultEndpointsProtocol=https;AccountName=cordenaaistg13344;AccountKey=SUA_CHAVE_AQUI;EndpointSuffix=core.windows.net"
  },
  
  "AzureStorage": {
    "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=cordenaaistg13344;AccountKey=SUA_CHAVE_AQUI;EndpointSuffix=core.windows.net",
    "Environment": "dev"
  }
}

appsettings.json (Produção)

{
  "AzureStorage": {
    "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=cordenaaistg13344;AccountKey=SUA_CHAVE_PROD;EndpointSuffix=core.windows.net",
    "Environment": "prod"
  }
}

2. Estrutura de Contêineres Hierárquicos

🔧 Desenvolvimento (Environment: "dev")

• dev-anexos - Container para arquivos gerais de desenvolvimento
• dev-imagens - Container para imagens de desenvolvimento (JPG, PNG, GIF)
• dev-documentos - Container para documentos de desenvolvimento (PDF, DOC, DOCX)
• dev-temporarios - Container para arquivos temporários de desenvolvimento
• dev-public-thumbnails - Container para thumbnails públicos de desenvolvimento

🚀 Produção (Environment: "prod")

• prod-anexos - Container para arquivos gerais de produção
• prod-imagens - Container para imagens de produção (JPG, PNG, GIF)
• prod-documentos - Container para documentos de produção (PDF, DOC, DOCX)
• prod-temporarios - Container para arquivos temporários de produção
• prod-public-thumbnails - Container para thumbnails públicos de produção

# Contêineres de desenvolvimento
az storage container create --name dev-anexos --account-name cordenaaistg13344
az storage container create --name dev-imagens --account-name cordenaaistg13344
az storage container create --name dev-documentos --account-name cordenaaistg13344
az storage container create --name dev-temporarios --account-name cordenaaistg13344
az storage container create --name dev-public-thumbnails --account-name cordenaaistg13344

# Contêineres de produção
az storage container create --name prod-anexos --account-name cordenaaistg13344
az storage container create --name prod-imagens --account-name cordenaaistg13344
az storage container create --name prod-documentos --account-name cordenaaistg13344
az storage container create --name prod-temporarios --account-name cordenaaistg13344
az storage container create --name prod-public-thumbnails --account-name cordenaaistg13344

3. Configuração de Serviços v2.0

// Configurar Azure Blob Storage com nova estrutura hierárquica
EstaAplicacao.GravarLog("|debug|Configurando Azure Blob Storage com nova estrutura...", "Startup.ConfigureServices()");

// Configurar AzureStorageConfig via IOptions
services.Configure<AzureStorageConfig>(
    Configuration.GetSection("AzureStorage"));

var azureStorageSection = Configuration.GetSection("AzureStorage");
var connectionString = azureStorageSection["ConnectionString"];
var environment = azureStorageSection["Environment"];

EstaAplicacao.GravarLog($"|info|Ambiente detectado: {environment}", "Startup.ConfigureServices()");

if (!string.IsNullOrEmpty(connectionString))
{
    // Registrar serviço com nova implementação hierárquica
    services.AddScoped<IBlobStorageService, BlobStorageService>();
    services.AddScoped<AnexoBlobService>();
    
    EstaAplicacao.GravarLog($"|sucesso|Azure Blob Storage configurado com ambiente: {environment}", "Startup.ConfigureServices()");
}
else
{
    EstaAplicacao.GravarLog("|aviso|Azure Storage connection string não encontrada - registrando implementação mock", "Startup.ConfigureServices()");
    // Registrar uma implementação mock para evitar erro de DI
    services.AddScoped<IBlobStorageService, MockBlobStorageService>();
}

Novos Componentes da Arquitetura

• AzureStorageConfig - Classe de configuração com ConnectionString e Environment
• ContainerType - Enum para tipos de contêineres (Imagens, Documentos, Anexos, etc.)
• BlobStorageService v2.0 - Implementação com suporte a contêineres hierárquicos
• MockBlobStorageService - Implementação mock para desenvolvimento sem Azure

Endpoints da API v2.0

✅ Como Funciona a Migração Automática

Quando você faz um upload via POST /api/anexos-blob/upload:

1. AnexoBlobService chama _blobStorageService.GetContainerByFileType(contentType)
2. BlobStorageService mapeia o tipo de arquivo para ContainerType (ex: image/jpeg → ContainerType.Imagens)
3. AzureStorageConfig aplica o prefixo do ambiente (ex: "dev" + "imagens" = "dev-imagens")
4. Arquivo é salvo no contêiner correto automaticamente

Tipos de Contexto

O parâmetro tipoContextoId do upload identifica o tipo de documento. A lista de tipos ativos pode ser obtida via GET /api/TipoContexto/ativos. Referência:

Upload de Arquivo

POST /api/anexos-blob/upload
Content-Type: multipart/form-data
Authorization: Bearer {token}

Parâmetros:
- file: IFormFile (obrigatório)
- tipoContextoId: int (obrigatório) — ID do tipo de contexto; ver seção "Tipos de Contexto" ou GET /api/TipoContexto/ativos
- entidade: string (obrigatório)
- usuarioUpload: string (opcional)
- tipoAnexo: int (opcional)

Resposta: 200 OK com AnexoBlobResponse
Conflito: 409 se já existe documento para usuário/contexto

Listagem de Anexos

GET /api/anexos-blob
Authorization: Bearer {token}
Resposta: Lista de todos os anexos ativos

GET /api/anexos-blob/usuario/{userId}
Authorization: Bearer {token}
Resposta: Lista de anexos do usuário específico

GET /api/anexos-blob/usuario/{userId}/contexto/{contexto}
Authorization: Bearer {token}
Resposta: Anexo específico por usuário e contexto

Operações por ID

GET /api/anexos-blob/{id}
Authorization: Bearer {token}
Resposta: Anexo específico ou 404 se não encontrado

PUT /api/anexos-blob/{id}
Authorization: Bearer {token}
Body: AtualizarAnexoBlobRequest
Resposta: Anexo atualizado ou 404 se não encontrado

DELETE /api/anexos-blob/{id}
Authorization: Bearer {token}
Resposta: Confirmação de exclusão (soft delete)

Download e URLs

GET /api/anexos-blob/{id}/download
Authorization: Bearer {token}
Resposta: Stream do arquivo para download

GET /api/anexos-blob/{id}/sas-url?expiryHours=1
Authorization: Bearer {token}
Resposta: URL SAS temporária (padrão: 1 hora)

Modelos de Dados v2.0

AzureStorageConfig

namespace InMinds.CordenaAi.Api.Infra.BlobStorage;

public class AzureStorageConfig
{
    public string ConnectionString { get; set; } = string.Empty;
    public string Environment { get; set; } = string.Empty;
    
    /// <summary>
    /// Gera o nome do contêiner com prefixo do ambiente
    /// Exemplo: "dev" + "imagens" = "dev-imagens"
    /// </summary>
    public string GetContainerName(string baseContainer)
    {
        return $"{Environment}-{baseContainer}";
    }
}

ContainerType (Enum)

namespace InMinds.CordenaAi.Api.Infra.BlobStorage;

/// <summary>
/// Tipos de contêineres disponíveis no Azure Blob Storage
/// </summary>
public enum ContainerType
{
    /// <summary>Imagens (JPG, PNG, GIF, etc.)</summary>
    Imagens,
    
    /// <summary>Documentos (PDF, DOC, DOCX, etc.)</summary>
    Documentos,
    
    /// <summary>Anexos gerais</summary>
    Anexos,
    
    /// <summary>Arquivos temporários</summary>
    Temporarios,
    
    /// <summary>Thumbnails públicos</summary>
    PublicThumbnails
}

UploadAnexoRequest

public class UploadAnexoRequest
{
    [Required(ErrorMessage = "Arquivo é obrigatório")]
    public IFormFile File { get; set; } = null!;

    [Required(ErrorMessage = "Contexto é obrigatório")]
    [StringLength(255, ErrorMessage = "Contexto deve ter no máximo 255 caracteres")]
    public string Contexto { get; set; } = string.Empty;

    [Required(ErrorMessage = "Entidade é obrigatória")]
    [StringLength(255, ErrorMessage = "Entidade deve ter no máximo 255 caracteres")]
    public string Entidade { get; set; } = string.Empty;

    [StringLength(255, ErrorMessage = "Usuário upload deve ter no máximo 255 caracteres")]
    public string? UsuarioUpload { get; set; }

    public int? TipoAnexo { get; set; }
}

AnexoBlobResponse

public class AnexoBlobResponse
{
    public int Id { get; set; }
    public string NomeDoArquivo { get; set; } = string.Empty;
    public string TipoDoArquivo { get; set; } = string.Empty;
    public long Tamanho { get; set; }
    public string BlobUrl { get; set; } = string.Empty;
    public string BlobContainer { get; set; } = string.Empty;
    public string BlobFileName { get; set; } = string.Empty;
    public string Contexto { get; set; } = string.Empty;
    public string Entidade { get; set; } = string.Empty;
    public string UsuarioUpload { get; set; } = string.Empty;
    public DateTime DataUpload { get; set; }
    public int? TipoAnexo { get; set; }
    public bool IsActive { get; set; }
    public string? CreatedBy { get; set; }
    public DateTime? UpdatedAt { get; set; }
}

AtualizarAnexoBlobRequest

public class AtualizarAnexoBlobRequest
{
    [Required(ErrorMessage = "Nome do arquivo é obrigatório")]
    [StringLength(255, ErrorMessage = "Nome do arquivo deve ter no máximo 255 caracteres")]
    public string NomeDoArquivo { get; set; } = string.Empty;

    [StringLength(255, ErrorMessage = "Contexto deve ter no máximo 255 caracteres")]
    public string? Contexto { get; set; }

    public int? TipoAnexo { get; set; }
}

AnexoEntity (Banco de Dados)

[Table("anexos")]
public class AnexoEntity
{
    [Key]
    [Column("id")]
    public int Id { get; set; }

    [Required]
    [Column("NomeDoArquivo")]
    [StringLength(255)]
    public string NomeDoArquivo { get; set; } = string.Empty;

    [Required]
    [Column("TipoDoArquivo")]
    [StringLength(255)]
    public string TipoDoArquivo { get; set; } = string.Empty;

    [Column("Tamanho")]
    public int? Tamanho { get; set; }

    [Required]
    [Column("Contexto")]
    [StringLength(255)]
    public string Contexto { get; set; } = string.Empty;

    [Required]
    [Column("Entidade")]
    [StringLength(255)]
    public string Entidade { get; set; } = string.Empty;

    [Required]
    [Column("UsuarioUpload")]
    [StringLength(255)]
    public string UsuarioUpload { get; set; } = string.Empty;

    [Required]
    [Column("DataUpload")]
    public DateTime DataUpload { get; set; }

    [Column("TipoAnexo")]
    public int? TipoAnexo { get; set; }

    // Campos específicos para Blob Storage
    [Column("BlobUrl")]
    [StringLength(500)]
    public string? BlobUrl { get; set; }

    [Column("BlobContainer")]
    [StringLength(100)]
    public string? BlobContainer { get; set; }

    [Column("BlobFileName")]
    [StringLength(255)]
    public string? BlobFileName { get; set; }

    [Column("IsActive")]
    public bool IsActive { get; set; } = true;

    [Column("CreatedBy")]
    [StringLength(255)]
    public string? CreatedBy { get; set; }

    [Column("UpdatedAt")]
    public DateTime? UpdatedAt { get; set; }
}

Serviços Implementados v2.0

IBlobStorageService v2.0

public interface IBlobStorageService
{
    // ===== NOVOS MÉTODOS v2.0 (ContainerType) =====
    Task<string> UploadAsync(Stream fileStream, string fileName, ContainerType containerType);
    Task<Stream> DownloadAsync(string fileName, ContainerType containerType);
    Task<bool> DeleteAsync(string fileName, ContainerType containerType);
    Task<List<string>> ListFilesAsync(ContainerType containerType);
    Task<bool> ExistsAsync(string fileName, ContainerType containerType);
    
    // ===== MÉTODOS DE COMPATIBILIDADE (mantidos) =====
    Task<string> UploadFileAsync(IFormFile file, string container);
    Task<bool> DeleteFileAsync(string blobUrl);
    Task<Stream> DownloadFileAsync(string blobUrl);
    Task<string> GenerateSasUrlAsync(string blobUrl, TimeSpan expiry);
    string GetContainerByFileType(string contentType); // 🔥 AGORA COM PREFIXOS!
}

🎯 Mapeamento Automático de Contêineres

O método GetContainerByFileType agora retorna nomes com prefixo de ambiente:

// Exemplo em Development (Environment = "dev"):
GetContainerByFileType("image/jpeg")  // Retorna: "dev-imagens"
GetContainerByFileType("application/pdf") // Retorna: "dev-documentos"
GetContainerByFileType("text/plain")     // Retorna: "dev-anexos"

// Exemplo em Production (Environment = "prod"):
GetContainerByFileType("image/jpeg")  // Retorna: "prod-imagens"
GetContainerByFileType("application/pdf") // Retorna: "prod-documentos"
GetContainerByFileType("text/plain")     // Retorna: "prod-anexos"

AnexoBlobService

public class AnexoBlobService
{
    // Métodos principais implementados:
    Task<AnexoBlobResponse> UploadAnexoAsync(UploadAnexoRequest request);
    Task<IEnumerable<AnexoBlobResponse>> ListarTodosAsync();
    Task<AnexoBlobResponse?> ObterPorIdAsync(int id);
    Task<IEnumerable<AnexoBlobResponse>> ListarPorUsuarioAsync(string userId);
    Task<AnexoBlobResponse?> ObterPorUsuarioEContextoAsync(string userId, string contexto);
    Task<AnexoBlobResponse?> AtualizarAsync(int id, AtualizarAnexoBlobRequest request);
    Task<bool> ExcluirAsync(int id);
    Task<Stream?> DownloadFileAsync(int id);
    Task<string?> GenerateSasUrlAsync(int id, TimeSpan expiry);
    Task<bool> ExistePorUsuarioEContextoAsync(string userId, string contexto);
}

Funcionalidades do BlobStorageService

• Upload: Gera nome único com GUID, salva metadados, organiza por container
• Download: Recupera arquivo do Azure Storage via URL
• Delete: Remove arquivo do Azure Storage
• SAS URLs: Gera URLs temporárias com expiração configurável
• Container Selection: Determina container baseado no tipo de arquivo
  • imagens/ para image/*
  • documentos/ para PDF, DOC, DOCX
  • anexos/ para outros tipos

Segurança

Autenticação

• Todos os endpoints requerem token JWT Bearer
• Validação de autorização por usuário

Validações

• Verificação de tipo de arquivo permitido (JPG, PNG, GIF, PDF, DOC, DOCX)
• Limite de tamanho de arquivo (10MB máximo)
• Validação de contexto obrigatório
• Verificação de duplicidade por usuário/contexto
• Validação de entidade obrigatória
• Soft delete para preservar histórico

URLs SAS

• URLs temporárias com expiração configurável
• Acesso seguro sem exposição de chaves
• Controle de permissões por tempo

Tratamento de Erros

Códigos de Status

• 200 - Sucesso
• 400 - Dados inválidos
• 401 - Não autorizado
• 404 - Anexo não encontrado
• 409 - Conflito (documento já existe)
• 500 - Erro interno

Mensagens de Erro

{
  "message": "Descrição do erro",
  "error": "Detalhes técnicos"
}

Monitoramento

Logs

• Upload de arquivos
• Erros de processamento
• Operações de blob storage
• URLs SAS geradas

Métricas

• Tamanho de arquivos
• Tempo de processamento
• Taxa de sucesso/erro
• Uso de storage

Limitações

Tamanho de Arquivo

• Máximo: 10MB por arquivo
• Tipos permitidos: JPG, PNG, GIF, PDF, DOC, DOCX

Performance

• Upload assíncrono com Azure Blob Storage
• Retry automático em falhas temporárias
• Metadados armazenados no banco de dados
• URLs SAS para acesso temporário
• Containers organizados por tipo de arquivo

Backup e Recuperação

Estratégia

• Replicação automática no Azure Storage
• Soft delete para preservar dados
• Metadados no banco de dados SQL Server/MySQL
• Logs de auditoria com timestamps

Recuperação

• Restauração por ID de anexo
• Recuperação por usuário/contexto
• Logs de auditoria com CreatedBy/UpdatedAt
• Histórico de alterações preservado

Troubleshooting

Problemas Comuns

1. Erro de conexão com Azure

   • Verificar connection string
   • Validar permissões da conta

2. Upload falha

   • Verificar tamanho do arquivo
   • Validar tipo de arquivo
   • Verificar autenticação

3. Download não funciona

   • Verificar se arquivo existe
   • Validar URL SAS
   • Verificar permissões

Logs Úteis

# Verificar logs da aplicação
dotnet run --verbosity detailed

# Logs do Azure Storage
az storage blob list --container-name anexos --account-name cordenaaistg13344

# Verificar containers criados
az storage container list --account-name cordenaaistg13344

📋 Changelog v2.0

🚀 Próximos Passos v3.0

Melhorias Planejadas

• ✅ Upload de arquivos para Azure Blob Storage
• ✅ URLs SAS temporárias
• ✅ Soft delete para preservar histórico
• ✅ Contêineres hierárquicos por ambiente
• ✅ Detecção automática de ambiente
• Compressão automática de imagens
• Thumbnails para imagens
• Criptografia de arquivos sensíveis
• Integração com CDN
• Análise de vírus
• OCR para documentos
• Versionamento de arquivos

Monitoramento Avançado

• Dashboard de métricas
• Alertas de capacidade
• Análise de uso
• Relatórios de auditoria